package tools.settings;

import java.io.File;
import java.util.*;
import javax.naming.directory.InvalidAttributesException;

/**
 *
 * @author Lynne Vandousselaere
 */
public interface Settings {

    /**
     * <p>Clear all settings from this object.</p>
     */
    void clear();

    /**
     * <p>Verifies if the given list of names of settings exists, and if not,
     * throws an invalidattributesexception.</p>
     *
     * @param snames
     *      the list of setting's names to be checked.
     * @throws javax.naming.directory.InvalidAttributesException
     */
    boolean contains(Collection<String> snames);

    /**
     * <p>Verifies if the given list of names of settings exists, and if not,
     * throws an invalidattributesexception.</p>
     *
     * @param snames
     *      the list of setting's names to be checked.
     * @throws javax.naming.directory.InvalidAttributesException
     */
    boolean contains(String[] snames);

    /**
     * <p>Returns all settings from a given type, or an clear list if these
     * settings don't have a type, or the type is not found.</p>
     *
     * @param type
     *      the settings type (e.g. gain)
     * @param dl
     *      filter on dl/ul. (dl=true, ul=false, no filter=null)
     * @return a list of setting names.
     */
    Collection<String> getSettingsByType(String type, boolean dl);

    /**
     * <p>Gets the list containing all locations of the settings, this
     * object represents.</p>
     *
     * @return a list of file with all locations, contained in this object.
     */
    List<File> getLocations();

    /**
     * <p>Returns all parameters, belonging to a certain setting (identified
     * by it's name). The parameters are returned as a map with key=name and
     * value=value of the parameter.</p>
     *
     * <p> Currently used parameternames are: "xmlns", "type", "qname" and
     * "value".</p>
     *
     * @param sname
     *      the setting's name
     * @return a map containing all parameters as (name-value) entries.
     */
    Map<String, String> getParameters(String sname);

    /**
     * <p>Returns the value of the given parameter of the given setting.</p>
     *
     * @param sname
     *      the setting's name
     * @param pname
     *      the parameter's name
     * @return the value of the given setting's parameter's name.
     */
    String getParameterValue(String sname, String pname);

    /**
     * <p>Returns the value of the given setting, or NULL if no setting
     * could be found with the given name.</p>
     *
     * @param sname
     *      name of the setting. (e.g. range)
     * @return the value of the given setting's name.
     */
    String getSettingsValue(String sname);

    /**
     * Attention! This is a special method, the sname will be transformed into
     * the correct sname (according to the given "dl") and this one's value
     * will be returned. Only few names are allowed here.
     * 
     * @param sname
     * @param dl
     *      filter on dl/ul. (dl=true, ul=false, no filter=null)
     * @return the value of the setting's name, taken into account the "dl/ul".
     */
    String getSettingsValue(String sname, boolean dl);

    /**
     * <p>Read in the settings for this object from a file or other object.</p>
     */
    public void readSettings(File sfile) throws SettingsReaderException;

    
}
